home *** CD-ROM | disk | FTP | other *** search
/ Aminet 51 / Aminet 51 (2002)(GTI - Schatztruhe)[!][Oct 2002].iso / Aminet / util / arc / xadmasterdev.lha / xad / Sources / clients / xadIO.doc < prev    next >
Encoding:
Text File  |  2002-08-20  |  22.4 KB  |  675 lines
  1. TABLE OF CONTENTS
  2.  
  3. xadIO/--general--
  4. xadIO/--Why use it--
  5. xadIO/--The sourcecode--
  6. xadIO/xadIOAlloc
  7. xadIO/xadIODropBitsHigh
  8. xadIO/xadIODropBitsLow
  9. xadIO/xadIOGetBitsHigh
  10. xadIO/xadIOGetBitsLow
  11. xadIO/xadIOGetChar
  12. xadIO/xadIOPutChar
  13. xadIO/xadIOReadBitsHigh
  14. xadIO/xadIOReadBitsLow
  15. xadIO/xadIOWriteBuf
  16. xadIO/xio_GetFunc
  17. xadIO/xio_InFunc
  18. xadIO/xio_OutFunc
  19. xadIO/xio_PutFunc
  20.  
  21. VERSION
  22.         $VER: xadIO.doc 1.1 (01.10.2001) by SDI
  23.  
  24. xadIO/--general--                                           xadIO/--general--
  25.  
  26.     How to use this xadIO-system? It is very easy. The callers side does
  27.     not known anything about the algorithm except its name.
  28.     An example call may look like this:
  29.  
  30.     struct xadInOut *io;
  31.  
  32.       if((io = xadIOAlloc(XADIOF_ALLOCINBUFFER|XADIOF_ALLOCOUTBUFFER
  33.       |XADIOF_NOCRC16, ai, xadMasterBase)))
  34.     {
  35.           io->xio_InSize = fi->xfi_CrunchSize;
  36.       io->xio_OutSize = fi->xfi_Size;
  37.           io->xio_CRC32 = ~0;
  38.  
  39.           switch(method)
  40.           {
  41.           case METHOD1: err = decrunchM1(io); break;
  42.           case METHOD2: err = decrunchM2(io); break;
  43.           case STORED: 
  44.             while(!(io->xio_Flags & (XADIOF_LASTOUTBYTE|XADIOF_ERROR)))
  45.               xadIOPutChar(io, xadIOGetChar(io));
  46.             err = io->xio_Error;
  47.             break;
  48.           default: err = XADERR_DATAFORMAT;
  49.           }
  50.  
  51.           if(!err)
  52.             err = xadIOWriteBuf(io);
  53.           if(!err && ~io->xio_CRC32 != crc)
  54.             err = XADERR_CHECKSUM;
  55.           xadFreeObjectA(io, 0);
  56.         }
  57.         else
  58.           err = XADERR_NOMEMORY;
  59.  
  60.     This easy structure can be expanded a lot. So it maybe necessary to
  61.     replace the xio_PutFunc() to do inline RunLength decoding or add input
  62.     and output functions for decryption and different checksum
  63.     calculations. All this is possible and very easy.
  64.     The STORED method shows an example how to copy the contents of the
  65.     file only. Normally the XADAC_COPY method should be used for that.
  66.     In case of password decryption or nonstandard checksum calculation,
  67.     the above is an easy way to do this in the same unique interface as
  68.     the decompression.
  69.  
  70.     The decompressors side does not know about this specials and only
  71.     does its work. Its side looks like that:
  72.  
  73.     static LONG decrunchM1(struct xadInOut *io)
  74.         {
  75.           struct priv *dat;
  76.           struct xadMasterBase *xadMasterBase = io->xio_xadMasterBase;
  77.  
  78.           if((dat = (struct priv *) xadAllocVec(sizeof(struct priv),
  79.           MEMF_CLEAR|MEMF_PUBLIC)))
  80.           {
  81.             /* init stuff */
  82.  
  83.             while(!(io->xio_Flags & (XADIOF_LASTOUTBYTE|XADIOF_ERROR)))
  84.             {
  85.               /* do something, use xadIOGetChar() and xadIOPutChar()
  86.                  or better use the bit functions if possible. */
  87.               /* Error codes are set in io->xio_Error TOGETHER with
  88.                  setting the flag XADIOF_ERROR. */
  89.             }
  90.             xadFreeObjectA(dat, 0);
  91.           }
  92.           return io->xio_Error;
  93.         }
  94.  
  95.     It maybe necessary to add additionally arguments to the function call
  96.     (e.g. the number of bits or global buffers for multifile compression
  97.     like in LZX). Generally it is best, if nothing of this is needed and
  98.     the algorithm allocates its bufferes itself. This makes reusing it
  99.     much easier.
  100.     
  101.     The io-structure also has a field for global windows used in multifile
  102.     compression (like in Ace).
  103.  
  104. xadIO/--Why use it--                                     xadIO/--Why use it--
  105.  
  106.     This system is very open and allows support of different decompression
  107.     routines.
  108.  
  109.     Some things, which are possible:
  110.     - The Input/Output functions maybe changed to calculate checksums,
  111.       encrypt, decrypt the data or even do another decompression step
  112.       (e.g. run length decoding) directly.
  113.     - The interface can be used to decrunch from file to file, from file
  114.       to memory, from memory to memory or from memory to file without any
  115.       additional work in the decrunching function.
  116.     - The system is not direct part of the xadmaster.library to make it
  117.       much faster (no system call interface inbetween. The functions are
  118.       really fast, but speed maybe improved by inlining the bits
  119.       functions directly. The source code provides mechanisms to do so.
  120.  
  121.     Thoughts about the implementation:
  122.     - The xadIOPutChar and xadIOGetChar interfaces aren't optimal when
  123.       compared to buffer based algorithms and anything like that. But
  124.       when doing tests the speed decrease is not really a problem.
  125.       This is because the put and get operations aren't most important
  126.       in modern compression algorithms anymore.
  127.     - The main advantage is an easy to use and powerful interface, which
  128.       is as fast as most other interfaces. And it is a standardized
  129.       interface.
  130.     - The reliability of the program code is increased when doing changes,
  131.       as often the code itself needs no modifications, but only new ways
  132.       to call (e.g. with CRC call, ...) are needed.
  133.     - It is very easy to reuse the algorithms (and most time algorithms
  134.       are used in different archiver systems).
  135.  
  136. xadIO/--The sourcecode--                             xadIO/--The sourcecode--
  137.  
  138.     The source code consists of 2 files called xadIO.h and xadIO.c.
  139.  
  140.     In case you want to use it as link library, call the file xadIO.h
  141.     from your sources always. This is like for any other module in your
  142.     project.
  143.     The link library is produced, when compiling the file xadIO.c with
  144.     the define XADIOFUNCMODE defined to "".
  145.  
  146.     The other way is calling xadIO.c from your source code. In this case
  147.     the functions default to be static and this maybe inlined in your
  148.     code. Defining the XADIOFUNCMODE to anything else than static may
  149.     change the type of the functions xadIOAlloc() and xadIOWriteBuf().
  150.     Changing XADIOFUNCMODEBITS allows you to change the bit functions
  151.     (e.g. make them inline functions). This define default to the value
  152.     of XADIOFUNCMODE normally.
  153.     You need to enable the required bit-functions in this mode. Define
  154.     following before calling the source file:
  155.     XADIOGETBITSHIGH
  156.     XADIOGETBITSLOW
  157.     XADIOREADBITSHIGH
  158.     XADIOREADBITSLOW
  159.  
  160. xadIO/xadIOAlloc                                             xadIO/xadIOAlloc
  161.  
  162.     NAME
  163.         xadIOAlloc - Allocate the xadInOut structure and necessary buffers
  164.  
  165.     SYNOPSIS
  166.         struct xadInOut * xadIOAlloc(ULONG flags, struct xadArchiveInfo *ai,
  167.                                      struct xadMasterBase *xadMasterBase)
  168.  
  169.     FUNCTION
  170.         This function allocates the xadInOut structure and initializes it.
  171.         Also required buffers are allocated.
  172.         The allocated structure is afterwards freed with xadFreeObjectA().
  173.         
  174.         The flags allow to change the behaviour of this function and other
  175.         functions of this system.
  176.  
  177.     XADIOF_ALLOCINBUFFER
  178.       This flags cause the function to allocate an input buffer.
  179.       If not set (e.g. when working from memory) the fields
  180.             xio_InBufferSize
  181.             xio_InBuffer
  182.           must be set after this function call.
  183.     XADIOF_ALLOCOUTBUFFER
  184.       This function causes the system to allocate an output buffer.
  185.       If not set (e.g. when working from memory) the fields
  186.             xio_OutBufferSize
  187.             xio_OutBuffer
  188.           must be set after this function call.
  189.     XADIOF_NOINENDERR
  190.       The function xadIOGetChar() does not produce an error at buffer
  191.       end, but inserts 0 characters as long as needed.
  192.     XADIOF_NOOUTENDERR
  193.       The function xadIOPutChar() does not check the size of output
  194.       stream, but outputs data anyway. This is required when the
  195.       output file size is not know before. Note that this has problems,
  196.       when extracting to memory, as the function xadIOWriteBuf() gets
  197.       called if buffer is full and needs to be flushed.
  198.     XADIOF_NOCRC16
  199.       Do not calculate standard CRC16. Saves some time. The CRC is
  200.       calculated in xadIOWriteBuf() function.
  201.     XADIOF_NOCRC32
  202.       Do not calculate standard CRC32. Saves some time. The CRC is
  203.       calculated in xadIOWriteBuf() function.
  204.     XADIOF_COMPLETEOUTFUNC
  205.       The supplied output-function does complete output itself. This maybe
  206.       necessary sometimes. Normally it only works with the output buffer
  207.       and lets xadWriteBuf() do the output.
  208.  
  209.     Although they cannot be passed as flags directly, here the description
  210.     of the missing flags. These are set by other functions to supply
  211.     status information:
  212.     XADIOF_LASTINBYTE
  213.       Is set in case the last input byte was read.
  214.     XADIOF_LASTOUTBYTE
  215.       Is set in case the last output byte was writen.
  216.     XADIOF_ERROR
  217.       Is set in case an error occured. This flag reduces the need to do
  218.       an additional check for error conditions.
  219.  
  220.     INPUT
  221.         flags         - XADIOF_xxx flags
  222.         ai            - Communication structure for buffer reads and stuff
  223.             like that. Maybe zero in case the xioIOGetChar() and
  224.             xadIOWriteBuf() functions need not access input or
  225.             output buffers.
  226.     xadMasterBase - The base library pointer.
  227.  
  228.     RESULT
  229.         ptr           - Pointer to xadInOut structure or zero for error.
  230.  
  231.     SEE ALSO
  232.         xadIO.h, xadIO.c, xadIOGetChar(), xadIOPutChar(), xadIOWriteBuf(),
  233.         xadFreeObjectA()
  234.  
  235. xadIO/xadIODropBitsHigh                               xadIO/xadIODropBitsHigh
  236.  
  237.     NAME
  238.         xadIODropBitsHigh - remove bits from higher end
  239.  
  240.     SYNOPSIS
  241.     void xadIODropBitsHigh(struct xadInOut *io, UBYTE bits)
  242.  
  243.     FUNCTION
  244.     This function maybe called to remove bits from imput. This is usually
  245.     done after calling xadIOReadBitsHigh(). This function is used with
  246.     xadIOReadBitsHigh() and xadDropBitsHigh(), but usage together with of
  247.     xadIOGetChar() and any of the functions ending in "Low" is strongly
  248.     discouraged.
  249.  
  250.     INPUT
  251.         io   - the xadInOut structure
  252.         bits - the number of bits to be read (maximum 24)
  253.  
  254.     SEE ALSO
  255.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar(), xadIODropBitsLow(),
  256.         xadIOReadBitsLow(), xadIOReadBitsHigh(), xadIOGetBitsLow(),
  257.         xadIOGetBitsHigh()
  258.  
  259. xadIO/xadIODropBitsLow                                 xadIO/xadIODropBitsLow
  260.  
  261.     NAME
  262.         xadIODropBitsLow - Remove bits from lower end
  263.  
  264.     SYNOPSIS
  265.         void xadIODropBitsLow(struct xadInOut *io, UBYTE bits)
  266.  
  267.     FUNCTION
  268.     This function maybe called to remove bits from imput. This is usually
  269.     done after calling xadIOReadBitsLow(). This function is used with
  270.     xadIOReadBitsLow() and xadDropBitsLow(), but usage together with of
  271.     xadIOGetChar() and any of the functions ending in "High" is strongly
  272.     discouraged.
  273.  
  274.     INPUT
  275.         io   - the xadInOut structure
  276.         bits - the number of bits to be read (maximum 24)
  277.  
  278.     SEE ALSO
  279.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar(), xadIODropBitsHigh(),
  280.         xadIOReadBitsLow(), xadIOReadBitsHigh(), xadIOGetBitsLow(),
  281.         xadIOGetBitsHigh()
  282.  
  283.  
  284. xadIO/xadIOGetBitsHigh                                 xadIO/xadIOGetBitsHigh
  285.  
  286.     NAME
  287.         xadIOGetBitsHigh - Gets bits from higher end
  288.  
  289.     SYNOPSIS
  290.     ULONG xadIOGetBitsHigh(struct xadInOut *io, UBYTE bits)
  291.  
  292.     FUNCTION
  293.     This function returns upto 24 bits read from input through
  294.     xadIOGetChar() function. The input bytes are shifted in from right
  295.     (least significant bits). The bits returned are taken from left
  296.     (most significant bits). The returned bits are removed from input.
  297.  
  298.     When using this function, xadIOReadBitsHigh() and xadDropBitsHigh()
  299.     maybe used as well, but usage of xadIOGetChar() and any of the
  300.     functions ending in "Low" is strongly discouraged.
  301.  
  302.     The function returns zero bits in case buffer ended or an error
  303.     occured.
  304.  
  305.     INPUT
  306.         io   - the xadInOut structure
  307.         bits - the number of bits to be read (maximum 24)
  308.  
  309.     RESULT
  310.         res  - upto 24 bits read from input
  311.  
  312.     SEE ALSO
  313.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar(), xadIOGetBitsLow(),
  314.         xadIOReadBitsLow(), xadIOReadBitsHigh(), xadIODropBitsLow(),
  315.         xadIODropBitsHigh()
  316.  
  317. xadIO/xadIOGetBitsLow                                   xadIO/xadIOGetBitsLow
  318.  
  319.     NAME
  320.         xadIOGetBitsLow - Gets bits from lower end
  321.  
  322.     SYNOPSIS
  323.     ULONG xadIOGetBitsLow(struct xadInOut *io, UBYTE bits)
  324.  
  325.     FUNCTION
  326.     This function returns upto 24 bits read from input through
  327.     xadIOGetChar() function. The input bytes are shifted in from left
  328.     (most significant bits). The bits returned are taken from right
  329.     (least significant bits). The returned bits are removed from input.
  330.  
  331.     When using this function, xadIOReadBitsLow() and xadDropBitsLow()
  332.     maybe used as well, but usage of xadIOGetChar() and any of the
  333.     functions ending in "High" is strongly discouraged.
  334.  
  335.     The function returns zero bits in case buffer ended or an error
  336.     occured.
  337.  
  338.     INPUT
  339.         io   - the xadInOut structure
  340.         bits - the number of bits to be read (maximum 24)
  341.  
  342.     RESULT
  343.         res  - upto 24 bits read from input
  344.  
  345.     SEE ALSO
  346.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar(), xadIOGetBitsHigh(),
  347.         xadIOReadBitsLow(), xadIOReadBitsHigh(), xadIODropBitsLow(),
  348.         xadIODropBitsHigh()
  349.  
  350. xadIO/xadIOGetChar                                         xadIO/xadIOGetChar
  351.  
  352.     NAME
  353.         xadIOGetChar - Gets one character
  354.  
  355.     SYNOPSIS
  356.         UBYTE xadIOGetChar(struct xadInOut *io)
  357.  
  358.         #define xadIOGetChar(io) (io)->xio_GetFunc((io))
  359.  
  360.     FUNCTION
  361.     This function reads one character from source. This calls the
  362.     xio_GetFunc function of the io-structure.
  363.  
  364.     The functions of io-structure shouuld never be called itself, but
  365.     always throught the xadIO functions.
  366.  
  367.     INPUT
  368.         io  - the xadInOut structure
  369.  
  370.     RESULT
  371.         res - one byte read from source
  372.  
  373.     SEE ALSO
  374.         xadIO.h, xadIO.c, xadIOAlloc(), xio_GetFunc()
  375.  
  376. xadIO/xadIOPutChar                                         xadIO/xadIOPutChar
  377.  
  378.     NAME
  379.         xadIOPutChar - Stores (one) character in output stream
  380.  
  381.     SYNOPSIS
  382.         UBYTE xadIOPutChar(struct xadInOut *io, UBYTE c)
  383.  
  384.     #define xadIOPutChar(io,a) (io)->xio_PutFunc((io), (a))
  385.  
  386.     FUNCTION
  387.     This function stores (one) character into destination. This calls the
  388.     xio_PutFunc function of the io-structure.
  389.  
  390.     The functions of io-structure shouuld never be called itself, but
  391.     always throught the xadIO functions.
  392.  
  393.     The related xio_PutFunc maybe used to do inline decompression (e.g.
  394.     RLE) and thus not necessary stores the passed byte or may store
  395.     more than one byte.
  396.  
  397.     INPUT
  398.         io  - the xadInOut structure
  399.         c   - the byte to store or process
  400.  
  401.     RESULT
  402.         res - the byte passed as argument
  403.  
  404.     SEE ALSO
  405.         xadIO.h, xadIO.c, xadIOAlloc(), xio_PutFunc, xadIOWriteBuf()
  406.  
  407. xadIO/xadIOReadBitsHigh                               xadIO/xadIOReadBitsHigh
  408.  
  409.     NAME
  410.         xadIOReadBitsHigh - Read bits from higher end
  411.  
  412.     SYNOPSIS
  413.     ULONG xadIOReadBitsHigh(struct xadInOut *io, UBYTE bits)
  414.  
  415.     FUNCTION
  416.     This function returns upto 24 bits read from input through
  417.     xadIOGetChar() function. The input bytes are shifted in from right
  418.     (least significant bits). The bits returned are taken from left
  419.     (most significant bits). The returned bits are NOT removed from input.
  420.  
  421.     The function xadIODropBitsHigh() maybe used to remove bits from input
  422.     stream. The number of removed bits needs not match the number or read
  423.     bits.
  424.  
  425.     When using this function, xadIOGetBitsHigh() maybe used as well, but
  426.     usage of xadIOGetChar() and any of the functions ending in "Low" is
  427.     strongly discouraged.
  428.  
  429.     The function returns zero bits in case buffer ended or an error
  430.     occured.
  431.  
  432.     INPUT
  433.         io   - the xadInOut structure
  434.         bits - the number of bits to be read (maximum 24)
  435.  
  436.     RESULT
  437.         res  - upto 24 bits read from input
  438.  
  439.     SEE ALSO
  440.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar(), xadIOReadBitsLow(),
  441.         xadIOGetBitsLow(), xadIOGetBitsHigh(), xadIODropBitsLow(),
  442.         xadIODropBitsHigh()
  443.  
  444. xadIO/xadIOReadBitsLow                                 xadIO/xadIOReadBitsLow
  445.  
  446.     NAME
  447.         xadIOReadBitsLow - Read bits from lower end
  448.  
  449.     SYNOPSIS
  450.     ULONG xadIOReadBitsLow(struct xadInOut *io, UBYTE bits)
  451.  
  452.     FUNCTION
  453.     This function returns upto 24 bits read from input through
  454.     xadIOGetChar() function. The input bytes are shifted in from left
  455.     (most significant bits). The bits returned are taken from right
  456.     (least significant bits). The returned bits are NOT removed from input.
  457.  
  458.     The function xadIODropBitsLow() maybe used to remove bits from input
  459.     stream. The number of removed bits needs not match the number or read
  460.     bits.
  461.  
  462.     When using this function, xadIOGetBitsLow() maybe used as well, but
  463.     usage of xadIOGetChar() and any of the functions ending in "High" is
  464.     strongly discouraged.
  465.  
  466.     The function returns zero bits in case buffer ended or an error
  467.     occured.
  468.  
  469.     INPUT
  470.         io   - the xadInOut structure
  471.         bits - the number of bits to be read (maximum 24)
  472.  
  473.     RESULT
  474.         res  - upto 24 bits read from input
  475.  
  476.     SEE ALSO
  477.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar(), xadIOReadBitsHigh(),
  478.         xadIOGetBitsLow(), xadIOGetBitsHigh(), xadIODropBitsLow(),
  479.         xadIODropBitsHigh()
  480.  
  481. xadIO/xadIOWriteBuf                                       xadIO/xadIOWriteBuf
  482.  
  483.     NAME
  484.         xadIOWriteBuf - Flushed output buffer
  485.  
  486.     SYNOPSIS
  487.         LONG xadIOWriteBuf(struct xadInOut *io)
  488.  
  489.     FUNCTION
  490.     This function is called from xadIOPutChar() in case the buffer is
  491.     full AND a new byte needs to be written! This is essential! It means
  492.     this function is never called if size of output buffer and output
  493.     file size are equal.
  494.  
  495.     It needs to be called directly after the sucessful extraction to flush
  496.     partial buffers.
  497.  
  498.     This behaviour allows to extract to memory directly without ever
  499.     calling this function.
  500.  
  501.     It also calculates CRC16 and CRC32 values and allows to call special
  502.     output functions processing the buffer. These functions may takeover
  503.     the complete output process (althought not recommended).
  504.  
  505.     INPUT
  506.         io  - the xadInOut structure
  507.  
  508.     RESULT
  509.         err - an XAD error code
  510.  
  511.     SEE ALSO
  512.         xadIO.h, xadIO.c, xadIOPutChar(), xadIOWriteBuf()
  513.  
  514. xadIO/xio_GetFunc                                           xadIO/xio_GetFunc
  515.  
  516.     NAME
  517.         xio_GetFunc - Gets one character
  518.  
  519.     SYNOPSIS
  520.         UBYTE xio_GetFunc(struct xadInOut *io)
  521.  
  522.         XADINOUTGET xio_GetFunc
  523.  
  524.     FUNCTION
  525.     This function reads one character from source. It is called through
  526.     the io-structure using the macro xadIOGetChar(). The standard function
  527.     is assigned by xadIOAlloc() and maybe replaced by own functions.
  528.  
  529.     Replacements need to take care of following:
  530.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  531.       set in case of errors.
  532.     - If XADIOF_NOINENDERR is not set the error code XADERR_DECRUNCH is
  533.       returned if no more bytes are available, else zero bytes are
  534.       returned.
  535.     - The function io->xio_InFunc must be called after complete buffer
  536.       reads.
  537.     - The field io->xio_InBufferPos needs to be used and set correctly.
  538.     - The field io->xio_InSize is decreased for every read byte.
  539.     - The Flag XADIOF_LASTINBYTE is set for last read byte.
  540.  
  541.     - The field io->xio_GetFuncPrivate is for private use.
  542.  
  543.     INPUT
  544.         io  - the xadInOut structure
  545.  
  546.     RESULT
  547.         res - one byte read from source
  548.  
  549.     SEE ALSO
  550.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOGetChar()
  551.  
  552. xadIO/xio_InFunc                                             xadIO/xio_InFunc
  553.  
  554.     NAME
  555.         xio_InFunc - Input processing buffer
  556.  
  557.     SYNOPSIS
  558.         void xio_InFunc(struct xadInOut *io, ULONG size)
  559.  
  560.         XADINOUTFUNC xio_InFunc
  561.  
  562.     FUNCTION
  563.     This function allows the preprocess the input buffer. This maybe used
  564.     to call decryption routines or checksum algorithms. It gets the
  565.     xadInOut structure and the buffer size as argument.
  566.     It is allow to modify the contents of xio_InBuffer from position zero
  567.     until passed size. Nothing else except the private pointer maybe
  568.     changed.
  569.     It does not support buffer expansion or size changes.
  570.  
  571.     This function is called from xadIOGetChar() or xio_GetFunc() after
  572.     reading a new buffer.
  573.  
  574.     Replacements need to take care of following:
  575.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  576.       set in case of errors.
  577.  
  578.     - The field io->xio_InFuncPrivate is for private use.
  579.  
  580.     INPUT
  581.         io   - the xadInOut structure
  582.         size - the input buffer size
  583.  
  584.     RESULT
  585.         none
  586.  
  587.     SEE ALSO
  588.         xadIO.h, xadIO.c, xadIOGetChar(), xio_GetFunc()
  589.  
  590. xadIO/xio_OutFunc                                           xadIO/xio_OutFunc
  591.  
  592.     NAME
  593.         xio_OutFunc - Output processing buffer
  594.  
  595.     SYNOPSIS
  596.         void xio_OutFunc(struct xadInOut *io, ULONG size)
  597.  
  598.         XADINOUTFUNC xio_OutFunc
  599.  
  600.     FUNCTION
  601.     This function allows the preprocess the output buffer. This maybe used
  602.     to call decryption routines or checksum algorithms. It gets the
  603.     xadInOut structure and the buffer size as argument.
  604.     It is allow to modify the contents of xio_OutBuffer from position zero
  605.     until passed size. Nothing else except the private pointer maybe
  606.     changed.
  607.  
  608.     This function is called from xadIOWriteBuf() before writing the
  609.     buffer. If the flag XADIOF_COMPLETEOUTFUNC is set, this function
  610.     also needs to store the output buffer using xadHookAccess().
  611.  
  612.     Replacements need to take care of following:
  613.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  614.       set in case of errors.
  615.  
  616.     - The field io->xio_OutFuncPrivate is for private use.
  617.  
  618.     INPUT
  619.         io   - the xadInOut structure
  620.         size - the output buffer size
  621.  
  622.     RESULT
  623.         none
  624.  
  625.     SEE ALSO
  626.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOWriteBuf(), xadHookAccess()
  627.  
  628. xadIO/xio_PutFunc                                           xadIO/xio_PutFunc
  629.  
  630.     NAME
  631.         xio_PutFunc - Stores (one) character in output stream
  632.  
  633.     SYNOPSIS
  634.         UBYTE xio_PutFunc(struct xadInOut *io, UBYTE c)
  635.  
  636.         XADINOUTPUT xio_PutFunc
  637.  
  638.     FUNCTION
  639.     This function stores (one) character into destination. It is called
  640.     through the io-structure using the macro xadIOPutChar(). The standard
  641.     function is assigned by xadIOAlloc() and maybe replaced by own
  642.     functions.
  643.  
  644.     This function maybe used to do inline decompression (e.g. RLE) and
  645.     thus not necessary stores the passed byte or may store more than
  646.     one byte.
  647.  
  648.     Replacements need to take care of following:
  649.     - The fields io->xio_Error and io->xio_Flags |= XADIOF_ERROR must be
  650.       set in case of errors.
  651.     - If XADIOF_NOOUTENDERR is not set the error code XADERR_DECRUNCH is
  652.       returned if no more bytes can be stored, else the additional bytes
  653.       are stored.
  654.     - The field io->xio_OutBufferPos needs to be used and set correctly.
  655.     - The field io->xio_OutSize is decreased for every read byte.
  656.     - The Flag XADIOF_LASTOUTBYTE is set for last read byte.
  657.     - The passed byte needs to be returned as result!
  658.     - If the buffer is full and a new byte needs to be stored
  659.       xadIOWriteBuf() needs to be called. Never before!
  660.  
  661.     - The field io->xio_PutFuncPrivate is for private use.
  662.  
  663.     INPUT
  664.         io  - the xadInOut structure
  665.         c   - the byte to store or process
  666.  
  667.     RESULT
  668.         res - the byte passed as argument
  669.  
  670.     SEE ALSO
  671.         xadIO.h, xadIO.c, xadIOAlloc(), xadIOPutChar(), xadIOWriteBuf()
  672.  
  673.  
  674.  
  675.